See also #50 #89 #97

it is worth saying that although this method is good at the initial stage, it does not give the desired severity of the types.

-> @return {Object.<string, WebGLBuffer>} The created sphere buffers

<string, here you need to specify the properties explicitly

@return {{
    position: WebGLBuffer,
    normal: WebGLBuffer,
    texcoord: WebGLBuffer,
    indices: WebGLBuffer,
  }} The created sphere buffers

for

Example:
     *
     *         const bufferInfo1 = twgl.createBufferInfoFromArrays(gl, {
     *           position: [1, 2, 3, ... ],
     *         });
     *         const bufferInfo2 = twgl.createBufferInfoFromArrays(gl, {
     *           position: bufferInfo1.attribs.position,  // use the same buffer from bufferInfo1
     *         });

This case should be taken into account in the typing, which I showed in my example
I'm not a big expert on how to do this through js-doc, but in ts..

I think a good solution would be to generate files for each file in src and correct them, and then make into Assembly by the ts compiler. Although this will require a lot of effort, it will ease the work with d.ts in the future.

I incorporated this PR into #97

Your python translated to node/js is here

I tested it builds. I didn't test that it runs or that I translated every regex correctly. To build

npm install
npm run build

To just build the type file

npm run buildts

<string, here you need to specify the properties explicitly

@return {{
    position: WebGLBuffer,
    normal: WebGLBuffer,
    texcoord: WebGLBuffer,
    indices: WebGLBuffer,
  }} The created sphere buffers

this doesn't feel right to me.

To me they should be documented as returning a map of strings to WebGLBuffer like

 Record<string, WebGLBuffer>

Closing this PR; please see #102 instead

Record<string, WebGLBuffer>

Why? this makes the code more complex
in ts you always rely on the types, and this type can not be relied on,
this at least contradicts the Occam's razor principle of good code

perhaps this description will look better, this is the option I showed in ts

Record<'position | 'normal' | 'indices' | 'texcoord', WebGLBuffer>

@pineapplemachine I'm not saying it's worth doing right now) but it's definitely worth it

I'd like to understand the call for stronger types. Record<string, WebGLBuffer> vs

@return {{
    position: WebGLBuffer,
    normal: WebGLBuffer,
    texcoord: WebGLBuffer,
    indices: WebGLBuffer,
  }} 

I have lots of C++/C# experience so I'm not allergic to types I don't really understand a hard coded type makes sense for attribute/buffer related things.

it's perfectly valid to do this

const buffers = createSphereBuffers(...);
buffers.colors = someWebGLBuffer;

Typing createSphereBuffers as returning some specific list doesn't make sense to me but maybe I don't understand the suggestion. In C++/C# making a hard coded type with 4 explicit proprties would mean adding a 5th property is prohibited. Is this different in typescript?

All the functions that deal with buffers, attributes, and uniforms are explicitly string based maps to objects. There is no special meaning . You can make a shader

attribute float foo;
attribute vec3 bar;

and then make arrays

const bufferInfo = twgl.createBufferInfoFromArrays(gl, {
  foo: { numComponents: 1, data: [1,2,3,4] },
  bar: { numComponents: 3, data[ 1, 2, 3, 4, 5, 6, 7, 8, 9, 11, 11, 12],
};

In general position, texcoord, normal etc are not special

Similarly you're equally free to do something like

const sphereArrays = twgl.primitives.createSphereArrays(10,20,30);
const arrays = {
     foo: { numComponents: 1, data: [1,2,3,4, ...] },
     bar: sphereArrays.position,
};

or like above

const sphereArrays = twgl.primitives.createSphereArrays(10,20,30);
sphereArrays.colors =  { numComponents: 3, data: [1,2,3,4, ...] };

I don't mind stronger types if typescript has some special way of saying "this thing is a map of strings to X and starts with these specific 4 things but youre free to add or remove more things to the map" but coming from C++/C# that can't be expressed there AFAIK so I'm assuming it also can't be expressed in typescript?

@greggman There are tools to work around that sort of situation in TypeScript, since it's just JS and dynamic typing under the hood. Here is one option that I think could work better than simply <string, WebGLBuffer> and may address your concerns:

interface ObjectWithAtLeastTheseProperties {
    a: string;
    b: string;
    c: string;
    [key: string]: string;
}

function doStuff() {
    const abc: ObjectWithAtLeastTheseProperties = {
        a: "apple",
        b: "bear",
        c: "clue",
    };
    abc.d = "door";
}

Another option is leaving it up to the dependent code to specify if they want to add any more properties to the object or not. For example, you could strictly define the input type as was first discussed and then in cases where somebody wanted to mess with the object's properties, they'd write something more like this:

const buffers = <[key: string]: WebGLBuffer> createSphereBuffers(...);
buffers.colors = someWebGLBuffer;

Or for even more freedom, something like this:

const buffers = <Object> createSphereBuffers(...);
buffers.colors = someWebGLBuffer;
buffers.whatever = "Hello, world!"

1) {  a?: T, b: T } &  {  a: T } === {  a: T, b: T }
2) { [key: keyof { a?: T, b: T } ]: K} === { a?: K, b: K }
3) <S extends { a?: T, b: T }>{ [key: keyof S ]: K} 
4) M = <S>{ [key: keyof (S & { a?: T, b: T }) ]: K} 
5) H = <S>{ [key: keyof (S & { a?: T, b: T }) ]: W}
6) G = <S, L>{ [key: keyof (S & { a?: T, b: T }) ]: L}
7) fn<A>(a: G<A, []>) : G<A, WebglBuffer>
8) buffers = fn(array) // fn<A> auto derived

See code not see where in it user-defined type of

return {
    position: positions,
    normal: normals,
    texcoord: texcoords,
    indices: indices,
  };

This is TRecord = Record<'position' | 'normal' | 'indices' | 'texcoord', WebGLBuffer>.

But user-defined type of

createBuffersFromArrays<TRecord, TUserArrayNames>(gl, arrays: Record<keyof TRecord & TUserArrayNames, []>): TRecord & Record<TUserArrayNames, WebGLBuffer> {}
// TUserArrayNames is derived from the arrays

or TUserArrayNames = keyof TUserArrayByName

and user use like:

const arrays: { abs: [], position: [] } = ... ;
const buffers:  Record<'position' | 'abs', WebGLBuffer> = createSphereBuffers(...); // and this type is derived from the arguments(arrays)

in c++ or c# u write code like

enum NameEnum {
    position,
    normal,
    texcoord,
    indices,
}
class Buffer<TNameEnum = NameEnum> whare TNameEnum: Enum {
    ...
   public WebGLBuffer this[TNameEnum i] 
   { 
     get { return arrayByName[i]; }  
   }
}

and user can create self enum or extends(i know what enum not extendable, but exists many ways escape this)